SHMCTL

Section: System Calls (2)
Index Return to Main Contents

BSD mandoc
NetBSD

NAME

shmctl - shared memory control operations

SYNOPSIS

Fd #include <sys/types.h> Fd #include <sys/ipc.h> Fd #include <sys/msg.h> Ft int Fn shmctl int shmid int cmd struct shmid_ds *buf

DESCRIPTION

The Fn shmctl system call performs some control operations on the shared memory area specified by Fa shmid .

Each shared memory segment has a data structure associated with it, parts of which may be altered by Fn shmctl and parts of which determine the actions of Fn shmctl .

This structure is defined as follows in Aq Pa sys/shm.h :

struct shmid_ds {
    struct ipc_perm shm_perm;     /* operation permissions */
    int             shm_segsz;    /* size of segment in bytes */
    pid_t           shm_lpid;     /* pid of last shm op */
    pid_t           shm_cpid;     /* pid of creator */
    short           shm_nattch;   /* # of current attaches */
    time_t          shm_atime;    /* last shmat() time*/
    time_t          shm_dtime;    /* last shmdt() time */
    time_t          shm_ctime;    /* last change by shmctl() */
    void           *shm_internal; /* sysv stupidity */
};

The Bf -literal ipc_perm Ef structure used inside the Bf -literal shmid_ds Ef structure is defined in Aq Pa sys/ipc.h and looks like this:

struct ipc_perm {
    ushort cuid; /* creator user id */
    ushort cgid; /* creator group id */
    ushort uid;  /* user id */
    ushort gid;  /* group id */
    ushort mode; /* r/w permission (see chmod(2)) */
    ushort seq;  /* sequence # (to generate unique msg/sem/shm id) */
    key_t key;   /* user specified msg/sem/shm key */
};

The operation to be performed by Fn shmctl is specified in Fa cmd and is one of:

IPC_STAT: Gather information about the shared memory segment and place it in the structure pointed to by Fa buf .
IPC_SET: Set the value of the shm_perm.uid shm_perm.gid and shm_perm.mode fields in the structure associated with Fa shmid . The values are taken from the corresponding fields in the structure pointed to by Fa buf . This operation can only be executed by the super-user, or a process that has an effective user id equal to either shm_perm.cuid or shm_perm.uid in the data structure associated with the shared memory segment.
IPC_RMID: Remove the shared memory segment specified by Fa shmid and destroy the data associated with it. Only the super-user or a process with an effective uid equal to the shm_perm.cuid or shm_perm.uid values in the data structure associated with the queue can do this.

The read and write permissions on a shared memory identifier are determined by the shm_perm.mode field in the same way as is done with files (see chmod(2)), but the effective uid can match either the shm_perm.cuid field or the shm_perm.uid field, and the effective gid can match either shm_perm.cgid or shm_perm.gid

RETURN VALUES

Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

ERRORS

Fn shmctl will fail if:

Bq Er EPERM: Fa cmd is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does the effective uid match either the shm_perm.uid or shm_perm.cuid fields of the data structure associated with the shared memory segment.
An attempt is made to increase the value of shm_qbytes through IPC_SET but the caller is not the super-user.
Bq Er EACCESS: The command is IPC_STAT and the caller has no read permission for this shared memory segment.
Bq Er EINVAL: Fa shmid is not a valid shared memory segment identifier.
cmd is not a valid command.
Bq Er EFAULT: Fa buf specifies an invalid address.

This document was created by man2html, using the manual pages.
Time: 16:28:59 GMT, April 18, 2022